(1) Read the notes here and those shown by clicking on the button "PrFlds Parameter Layout".
(2) Copy a card, from a stack you want printed, to the end of this stack.
(3) Arrange the fields the way you want then printed on the page (location, size, font, etc.).
(4) Return to this card. Click on the "Build Print Specs" button on this card and answer the questions.
(5) Make any embellishments to the Specs that you want (see instructions in Parameter Layout text).
(6) Click on the "print example" button.
(7) Install PrFlds XCMD into your stack, copy the specs field (with contents) and print button into your stack.
ABOUT THIS XCMD:
PrFlds is an external command (XCMD) that gives general purpose printing capabilities for the content of background fields of a stack. This version (2.3) is limited to 100 fields (or items) per card.
PrFlds allows for specification of text areas for each background field. These text areas may be anywhere on the printed page and of any size and the text in the area may be any one of any fonts recognized by the System, any size, style, line height and justification. The text area may also be enclosed by a box. Text may cover more than one page if needed.
The collection of fields printed from a card (hereafter called a Record) may also be printed in columns on the page. For example, the definitions of the text areas for a record may fit within a space 3.5 inches wide by 3.5 inches high (thus printing in two columns with three records per column). The text printed may be the contents of a background field, any other text, or even the evaluation of a HyperTalk expression (e.g. the long date). The pages of the report produced by PrFlds may also have a title line, including page numbers.
Selection criteria can be specified, in the form of a HyperTalk function handler and located in the stack or background script. With this option, a certain subset of the cards of the background may be printed.
Click on the button "PrFlds Parameter Layout" for a description of the calling methods of PrFlds.
Changes in PrFlds to make version 1.9: a MAJOR bug fix (a problem if more objects were specified than the number of bkgnd fields). Also better error recovery, i.e. if something goes wrong, it should return properly.
Changes in PrFlds to make version 2.0: the capability was added to define "bottomless" fields, i.e. you can have a field print for the length of its contents, even over a page boundary. See the definition of items 4 and 5 of the objects line definitions in the "PrFlds Parameter Layout" for a description. ALSO - if you use the "preview" option, you now get a message in the lower right corner instead of the middle of the screen. The "Quick" option was added to allow printing without the annoying dialog box. The change between 2.0b4 and 2.0b5 fixed a bug on the validation of the print record. Also fixed was a bug where Chicago font was being changed to Geneva. A final fix (really?!) was made to PrFlds so that if HyperCard switched graph ports during the process, PrFlds switched back. This fixes a problem that usually only shows up on the AppleTalk Imagewriter where parts of pages do not print.
Other Changes: PrFlds now recognizes the ASCII formfeed character (Hex 0C) and starts the following text on the next page. A top margin can now be specified separate from the record spacing gap.
PRFlds is Copyright © 1990, University of Utah Computer Center (MEB 3440), Salt Lake City, Utah 84112
PrFlds was written by Joseph F. Buchanan at the University of Utah Computer Center and is available for use by anyone provided that proper credit is given for it and its use is not for profit. Inquiries and questions may be directed to me at the University of Utah Computer Center at (801) 581-6802 or AppleLink: A91, or bitnet: Joseph@UUCC.Utah.edu .
-- part contents for card part 17
----- text -----
How to call PrFlds
PrFlds is VERY general purpose and is therefore rather detailed in its specifications. Most of the specifications need to be loaded into a variable (container) and the name of the variable is then passed as the first parameter to the XCMD. The second parameter specifies options and the third parameter (if needed) contains the name of a handler (hyperTalk function handler found in the background or stack script). LIMITS: This version of PrFlds (2.3) is limited to 100 objects per record (card) in the report.
As PrFlds returns, you can find two pieces of information stored in global variables:
PagesPrinted - the actual number of pages that were printed by PrFlds
Version - the current version number of PrFlds, in the form: nn.n mm/dd/yy (this is also shown on
the screen if you specify the "V" option as shown below).
The options available to PrFlds are as follows:
ΓÇóN - Do not send output to the printer. Instead, show the output on the screen. This will show a test page.
ΓÇóB - Process cards only of this background (of the card showing when PrFlds is invoked).
Note: if all cards are processed and different backgrounds are encountered where ANY of the specified fields do not exist for that particular background, an error will occur and the print process will fail.
ΓÇóL - Lock the screen - do not show each card as it is processed. This speeds things up a bit.
ΓÇóP - Do a Page Setup dialog. This is useful for specifying page orientation and size.
ΓÇóQ - Quick printing - really, this means that the normal print dialog is bypassed.
ΓÇóS - Look for selection criterea in a HyperTalk function (the name of which is in the third parameter).
ΓÇóT - print the title (see line 1, item 5) on each page (also the page number)
ΓÇóU - Underline, i.e. draw a line on the page after each record (all fields printed for each card).
ΓÇóV - Show the version of PrFlds. This will appear in a dialog box before printing begins.
Example:
prFlds "specs","BSUP","ChooseCard(23)"
and the "ChooseCard" hyperTalk function handler returning TRUE or FALSE. This feature is described in detail if you click on the "Special Selection Function" button below.
The example shown will display a Page Setup dialog before printing. When printing, it will select only those cards of the background satisfy the condition specified in the function ChooseCard. A line will be drawn after each record.
The "Specs" information is as follows:
ΓÇó line 1:
ΓÇó item 1: The number of cards to be printed (or examined). This is usually the number of cards of the
background or stack. If, instead, you desire to print multiple copies if one record (the
contents of the current card), then precede this number by the letter "R".
ΓÇó item 2: The number of columns per page. The ENTIRE page layout makes up a column here, not
individual fields.
NOTE - Column boundaries are calculated by dividing the
number of columns into the page width. If the size and location parameters of individual fields
exceed these boundaries, those areas of the printed page will be overwritten.
ΓÇó item 3: The number of objects to be printed in the record. This includes each field as well as other
information that is specified in the subsequent lines of this "Specs" information area. This is
usually the number of lines of "Specs" minus 1.
ΓÇó item 4: The size of the gap showing between records (and at the top of the page). If this number is
followed by a slash (/) and another number, that number specifies the top of page margin.
ΓÇó item 5: The title to show at the top of each page. If there is something in this item, even if it is a
space character, then a title will be printed, along with a page number, otherwise no title nor
page numbers will be printed.
ΓÇó all other lines (one line per object or field):
ΓÇó item 1: Object identification - one of the following:
a. The background field ID number (a positive number).
OR
b. The negative value of a background field ID number - The name of the background field is to
be printed instead of its value.
OR
c. The letter "X" - in this case the text found in item 12 will be evaluated as a HyperTalk
expression and used in this place.
OR
d. The number "0" - The text in item 12 is to be printed as is.
NOTE: If item 12 is blank for choices c or d above, then no text will be printed, rather, a line will
be drawn connecting the points specified in items 2 and 3 with those in items 4 and 5.
ΓÇó items 2 and 3: The coordinates of the left top corner of the rectangle to contain the text specified in
item 1.
ΓÇó items 4 and 5: The coordinates of the right bottom corner of the rectangle to contain the text
specified in item 1. If you want the field to conform to the actual needs of the text, then precede
item 5 with an asterisk (e.g. *175). This will also allow the field to expand, going onto a subsequent
page if necessary. Please be aware that with this option, no other fields should be placed below this
rectangle, because they may be overwritten. If this feature is used, then page counting estimates
may be unreliable. The text rectangle bottom specified will be honored and the minimum length will
be used, even if that much space is not needed, but more will be used if needed. You can only have
10 fields go over a page boundary at a time, but that shouldn't be a problem.
NOTE: The coordinates are specified in the same manner as that of the Macintosh screen, i.e. the top
left corner of the screen is 0,0 and the bottom right is 512,342. Paper sizes are appropriately
larger with the size being approximately 75 dots per inch. PrFlds DOES NOT check to see if page
boundaries are exceeded. If you specify areas beyond the physical page, the specified text will not
show. Also, note that if a box os to be drawn around a text object, it will appear a few pixels
beyond the specified rectangle and can therefore be drawn off the edge of the page.
ALSO: As explained in item 1, a line may be drawn from the point defined by items
2 and 3 to the point defined by items 4 and 5.
ΓÇó item 6: The Font name. This can be any font name as recognized by the System.
ΓÇó item 7: The Font size.
ΓÇó item 8: The text height (the height of the line).
ΓÇó item 9: The text style. Use the first letter of the style. Combine as many as you like. These can
ΓÇó item 10: The text alignment: Center, Left or Right.
ΓÇó item 11: Border? If yes, then a border is drawn around the text box, otherwise not. If you enter a
"G" here, PrFlds will try to make a gray box in the area of the rectangle. This works for
the LaserWriter.
ΓÇó item 12: A text description. This is treated as a comment and ignored unless item 1 is "0" or "X".
A button has been programmed on this card to take a card of background fields and construct a print specifications list based on those background fields. You can copy a card from your stack and paste it into this stack and then use the button to see how to construct the print specifications. You may not want the same arrangement of fields in your printed report as is on your card, so you might first re-adjust the location of your fields and eliminate some fields from the constructed list. You may also wish to embellish the record with other objects like field names, additional information and borders.
Note: The physical size on the paper of the area to contain the record objects is determined by the rectangles specified for the record objects. The highest number of the item 4 parameters of the objects list is used as the height of the record rectangle. The height of the record plus the record gap will be used to determine how many records can fit on a page. The exception to this is when an object definition has an asterisk preceding the item 4 number, then the object print area will expand down as far as is needed. IF A FIELD IS CONTINUED TO ADDITIONAL PAGES, then the top of itsrectangle is set to the top of the page. Be sure to not have more than one continuing field in the same vertical space or else they will be overwritten.
AND.. as of version 2.2, PrFlds will recognize the ASCII FormFeed character (0C in hex, 12 in decimal), and will break the print at that point and continue it on the next print area (next page is assumed, but if more than 1 print area fits on a page, so will the continuations). The only problem with FormFeed characters, is that Hypercard insists on removing control characters from fields. You can embed the character by using NumToChar(12) into your fields.
PrFlds will put out the number of pages actually printed. You will find this number in the global variable: PagesPrinted. If you specify a page range, PrFlds will go through the motions of printing any previous pages (taking some time) then it will begin work on the specified pages. Depending on the size needed for expandable fields, this page count may not be correct.
Other Notes:
As PrFlds works, it examines all cards, the cards will appear on the screen as they are considered.
As the report is being printed, a status is shown in the message window showing the approximate progress (by page number being processed and percent of cards of the stack). This progress is only an approximate and may not be totally accurate.
Printing will not actually begin until the entire report is processed. Then if the print does not happen, it may be that there was not enough room on the system disk or in memory to assemble the report (or else that disk was locked).
-- part contents for card part 18
----- text -----
In printing your information from a stack, you may want to extract a subset from the total collection of cards of the background. The third parameter to the PrFlds XCMD will be used to make the determination whether a particular card is to be printed.
The following is the method loop of card examination:
ΓÇó a. If the S option is specified, then evaluate the function whose name is found in the third parameter.
- if the returned value of the function is FALSE, then ignore the card
b. if the S option is not specified, OR if the value returned is TRUE, then process the card.
ΓÇó Go to the next card of this background.
The function will usually be a hyperTalk function handler that you put in the background or stack script, but it might also be something else that returns TRUE or FALSE.
An example is as follows:
prFlds "specs","S","ChooseCard(23)"
function ChooseCard xxx
if field age>xxx then
return TRUE
else
return FALSE
end if
end ChooseCard
The card will be chosen if it has a value in the background field AGE of greater than 23.
ADDITIONAL INFORMATION:
In most cases, a Control-period will terminate the process of printing. Sometimes the XCMD might be in your function at the time of some loop problem. Therefore PrFlds was designed to also look for a "Cancel" to be returned from the function and then cancel the entire print process. A use of this is shown below:
function ChooseCard xxx
if the commandKey is down then -- Note: we cannot check for a period, only the commandKey
return "Cancel"
exit ChooseCard
end if
if field age>xxx then
return TRUE
else
return FALSE
end if
end ChooseCard
In this example, if you hold the command key down while the selection function is invoked, the "Cancel" message will be returned to PrFlds and the process will terminate.
-- part contents for card part 19
----- text -----
2.3.1
-- part contents for card part 20
----- text -----
The "Build Print Specs" button is supplied to give you a method for creating the printing specifications graphically. You should copy a card from your stack into this stack and re-arrange the fields and set their display attributes (font/size/style, etc.) to the way you might want them printed. Then click on the "Build" button and specify the card number. The button will then construct a field containing the printing specifications. You can then look at them and make adjustments as necessary. Unfortunately, this method is not very good for laying out onto complete pages (because of Hypercard's screen limitations), but you can at least get a good idea of how to lay out the fields. When you are ready to set up your stack for printing, you will need to store your print specifications in a field or script in your stack so that you can load a variable and send it to PrFlds to have it do the printing. See the script of the "Print example" button to see how this could be done.
